Module log | Tarantool

Module log

Tarantool provides a set of options used to configure logging in various ways: you can set a level of logging, specify where to send the log’s output, configure a log format, and so on. The log module allows you to configure logging in your application and provides additional capabilities, for example, logging custom messages and rotating log files.

Below is a list of all log functions.

Name Use
log.cfg({}) Configure a logger
log.error()
log.warn()
log.info()
log.verbose()
log.debug()
Log a message with the specified level
log.pid() Get the PID of a logger
log.rotate() Rotate a log file
log.new() Create a new logger with the specified name
log.cfg({})

Configure logging options. The following options are available:

  • level: Specify the level of detail the log has.

    The example below shows how to set the log level to verbose:

    local log = require('log')
    log.cfg { level = 'verbose' }
    

    See also: log.level.

  • log: Specify where to send the log’s output, for example, to a file, pipe, or system logger.

    Example 1: sending the log to the tarantool.log file

    log.cfg { log = 'tarantool.log' }
    

    Example 2: sending the log to a pipe

    log.cfg { log = '| cronolog tarantool.log' }
    

    Example 3: sending the log to syslog

    log.cfg { log = 'syslog:server=unix:/dev/log' }
    

    See also: log.to.

  • nonblock: If true, Tarantool does not block during logging when the system is not ready for writing, and drops the message instead.

    See also: log.nonblock.

  • format: Specify the log format: ‘plain’ or ‘json’.

    See also: log.format.

  • modules: Configure the specified log levels for different modules.

    See also: log.modules.

log.error(message)
log.warn(message)
log.info(message)
log.verbose(message)
log.debug(message)

Log a message with the specified logging level. You can learn more about the available levels from the log.level option description.

Example

The example below shows how to log a message with the warn level:

log.warn('Warning message')
Parameters:
  • message (any) –

    A log message.

    • A message can be a string.
    • A message may contain C-style format specifiers %d or %s. Example:
      log.info('Tarantool version: %s', box.info.version)
      
    • A message may be a scalar data type or a table. Example:
      log.error({ 500, 'Internal error' })
      
Return:

nil

The actual output will be a line in the log, containing:

  • the current timestamp
  • a module name
  • ‘E’, ‘W’, ‘I’, ‘V’ or ‘D’ depending on the called function
  • message

Note that the message will not be logged if the severity level corresponding to the called function is less than log.level.

log.pid()
Return:A PID of a logger. You can use this PID to send a signal to a log rotation program, so it can rotate logs.
log.rotate()

Rotate the log. For example, you need to call this function to continue logging after a log rotation program renames or moves a file with the latest logs.

Return:nil
log.new(name)

Since: 2.11.0

Create a new logger with the specified name. You can configure a specific log level for a new logger using the log.modules configuration property.

Parameters:
  • name (string) – a logger name
Return:

a logger instance

Example

This example shows how to set the verbose level for module1 and the error level for module2 in a configuration file:

log:
  modules:
    module1: 'verbose'
    module2: 'error'
app:
  file: 'app.lua'

To create the module1 and module2 loggers in your application (app.lua), call the new() function:

-- Creates new loggers --
module1_log = require('log').new('module1')
module2_log = require('log').new('module2')

Then, you can call functions corresponding to different logging levels to make sure that events with severities above or equal to the given levels are shown:

-- Prints 'info' messages --
module1_log.info('Info message from module1')
--[[
[16300] main/103/interactive/module1 I> Info message from module1
---
...
--]]

-- Swallows 'debug' messages --
module1_log.debug('Debug message from module1')
--[[
---
...
--]]

-- Swallows 'info' messages --
module2_log.info('Info message from module2')
--[[
---
...
--]]

At the same time, the events with severities below the specified levels are swallowed.

Example on GitHub: log_new_modules.

Found what you were looking for?
Feedback